.\" Copyright Petr Hracek, 2016
.\"
.\" This page is distributed under GPL.
.\"
.TH preupgrade-assistant-api 1 2016-09-01 "" "Linux User's Manual"
.SH NAME
preupgrade-assistant-api \- The Preupgrade Assistant API provides a set of functions
and variables which can be used for creating modules.

.SH AVAILABLE FUNCTIONS
API provides a set of functions which can be used for better handling of your data.

\fBcheck_applies_to\fP - The function can be used to detect a specific RPM package. If the RPM package does not exist, check the script exit with the \fBexit_not_applicable\fP return code.

\fBbackup_config_file\fP - The function backs up a config file to the \fB/root/preupgrade\fP directory.

\fBservice_is_enabled\fP - The function checks if the service provided by the chkconfig command is enabled.

.SH COMMON_DATA

There are several log files gathered before the assessment:

\fB$VALUE_RPM_QA\fP - all packages with RSA HEADER and php signature

\fB$VALUE_ALL_CHANGED\fP - all changed package files

\fB$VALUE_CONFIGCHANGED\fP - all changed configuration files

\fB$VALUE_RPM_RHSIGNED\fP - all RPM Packages signed by Red Hat

\fB$VALUE_PASSWD\fP - a file with all users

\fB$VALUE_GROUP\fP - a file with all groups

\fB$VALUE_CHKCONFIG - a file with the \fBchkconfig\fP output

\fB$VALUE_TPM_PREUPGRADE\fP - a directory used for storing your data (such as Kickstart and postupgrade.d directories)

\fB$VALUE_ALLMYFILES\fP - all local files

\fB$VALUE_EXECUTABLES\fP - all executables files

\fB$MIGRATE\fP - set to 1 if the migration mode is specified by the module

\fB$UPGRADE\fP - set to 1 if the upgrade mode is specified by the module


There are several directories located in \fB/root/preupgrade\fP which are used by the \fBpreupg\fP command

\fBkickstart\fP - used for the Kickstart generation.

\fBetc\fP - stored configuration files copied by modules.

\fBpostupgrade.d\fP - stored scripts which are executed after the upgrade.

\fBpreupgrade-scripts\fP - stored scripts which are executed before the upgrade.

\fBcommon\fP - the results of long term commands gathered before the assessment

.SH RETURN CODES
\fBexit_pass\fP - The test passed. Used if nothing "broken" was detected.

\fBexit_not_applicable\fP - The rule did not apply to the test target (e.g., the package is not installed).

\fBexit_informational\fP - The rule was evaluated by the checking engine but is not to be scored. Ideal for informational results, which have a "migration guide" chapter style.

\fBexit_fixed\fP - The rule failed but was fixed later. Ideal if you automatically fixed some configuration file/incompatibility. No manual review is expected but the user should be notified..

\fBexit_error\fP - An error occurred and the test could not be completed because the script failed while doing its job. Should be used in an "assert way", not as a common result.

\fBexit_fail\fP - The test failed. Moving to a new release with this configuration will result in malfunction. Use when you expect some action from the user - when the migration solution was not completed automatically.

Your script should also tell the administrator how risky it is to upgrade your component. This can be done with api functions log_{slight,medium,high,extreme}_risk.

.SH AVAILABLE RETURN CODES IN REPORTS
\fBpass\fP - The same as in RETURN CODES

\fBnot_applicable\fP - The rule did not apply to the test target (e.g., the package is not installed).

\fBinformational\fP - The rule was evaluated by the checking engine, but is not to be scored. Ideal for informational results, which have a "migration guide" chapter style.

\fBfixed\fP - The rule failed but was fixed later. Ideal if you automatically fixed some configuration file/incompatibility. No manual review is expected but the user should be notified.

\fBerror\fP - An error occurred and the test could not be completed because the script failed while doing its job. Should be used in an "assert way", not as a common result.

\fBneeds_inspection\fP - The test failed with the exit_fail return code but the module developer added one of these logs (log_{slight|medium}_risk before exit_fail.

\fBneeds_action\fP - The test failed with the exit_fail return code but the module developer added the log_high_risk before exit_fail.

\fBfail\fP - The test failed. The in-place upgrade is not recommended and marked as an EXTERME risk.

.SH RISK ASSESSMENT LEVELS
The available risk assessment levels are:

\fBSlight\fP - We assessed this field and have not found any issues. However, there is still a risk that not all variants have been covered.

\fBMedium\fP - It is likely that the area will cause a problem in case of the in-place upgrade. It needs to be checked by the administrator after the in-place upgrade and after the system has been monitored for some time.

\fBHigh\fP - The in-place upgrade cannot be used without the administrator's assistance. This typically involves some known broken scenario, existing 3rd party packages. After the administrator manually fixes the issue, it may be possible to perform the in-place upgrade, but it is not recommended.

\fBExtreme\fP - We found an incompatibility which makes the in-place upgrade impossible. It is recommended to install a new system with the help of the Preupgrade Assistant remediations.

The levels None, Slight and Medium change return code exit_fail to exit_needs_inspection. The level High changes exit_fail to exit_needs_action.

.SH LOGGING

There are several functions which do logging:

\fBlog_{debug,info,warning,error} <message>\fP

The function creates logs in the format:

<SEVERITIES> <TIMESTAMP> <MESSAGE>

.SH INI FILE EXAMPLE

Ini file example
.nf
\& [preupgrade]
\& content_title: <a title>
\& content_description: <a description of the module>
\& author: <the author's name and email>
\& applies_to: <a package name (RPM) which is tested>
.fi

.SH AUTHORS
Petr Hracek, <phracek@redhat.com> (man page)
